/*
 * BBDBroker.java
 *
 * Created on January 21, 2007, 8:54 AM
 *
 * To change this template, choose Tools | Template Manager
 * and open the template in the editor.
 * 

 *
 */

package bbd;
/*
 * Copyright 2007 microneering, Inc and James Gamber
 * 
 * Licensed under the Apache License, Version 2.0 (the "License"); you may not
 * use this file except in compliance with the License. You may obtain a copy of
 * the License at
 * 
 * http://www.apache.org/licenses/LICENSE-2.0
 * 
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
 * License for the specific language governing permissions and limitations under
 * the License.
 * 
 * BBD/bbd/BBDBroker.java
 */
/**
 * Brokers provide methods for basic Create, Update, Delete (CRUD) functions.
 * 
 * Extended classes operate on groups of stored procedures, such as: testInsert
 * testUpdate testDelete
 * 
 * These stored procedures may be operating on one table or various tables
 * internal to the stored procedure. But the broker and the stored procedrues
 * represent a logical grouping in the applications business data model.
 * 
 * @author james gamber
 */
public interface BBDBroker<R extends BBDRow, L extends BBDRowArrayList<R>> {

	/**
	 * Select information from database.
	 * 
	 * @param row
	 *            An BBDRow that contains the parameters used by the select
	 *            method. <BR>Generally, parameters are used in the where clause
	 *            of an select SQL statement to decrease the number of rows
	 *            selected.
	 * 
	 * @return An array list containting the rows resulting from the select.
	 */
	public L select(R row);

	/**
	 * Insert information into database
	 * 
	 * @param row
	 *            Information to insert.
	 * @return number of row affected.
	 */
	public int insert(R row);

	/**
	 * Insert multiple rows of information into database
	 * 
	 * @param list
	 *            Rows of information to insert.
	 * @return number of row affected.
	 */
	public int insert(L list);

	/**
	 * Update information in database
	 * 
	 * @param row
	 *            Information used for update.
	 * @return number of row affected.
	 */
	public int update(R row);

	/**
	 * Update multiple rows of information in database.
	 * 
	 * @param list
	 *            Rows of information used for update.
	 * @return number of row affected.
	 */
	public int update(L list);

	/**
	 * Delete information in database
	 * 
	 * @param row
	 *            Information used to delete row from database.
	 * @return number of row affected.
	 */
	public int delete(R row);

	/**
	 * Delete multiple rows of information in database.
	 * 
	 * @param list
	 *            List of information to performs multiple deletes from
	 *            database.
	 * @return number of row affected.
	 */
	public int delete(L list);
	
	/**
	 * The broker creates connections to the database using a specified
	 * user name and password.  User/pw may be hard coded in the broker, 
	 * or set each time a broker is created or used.
	 * 
	 * @param name		name used for database connection
	 * @param password  password used for database oonnection
	 */
	public void setPrincipal(final String name, final String password);

}
